.. _monitoring:

Monitoring
============

Starting with LinOTP 2.8.1 a new monitoring API was introduced. It can be used
to query information about license, configuration as well as token and user numbers.

The comprehensive API documentation can be found here:

https://www.linotp.org/doc/api/linotp.controllers.monitoring.html

The basic API call is:

``https://<LINOTP>/monitoring/<MonitoringController>?session=SESSIONCOOKIE[&PARAM1][&PARAM2][..]``

.. tip::
 Detailed information about the handling of the session cookie can be found at
 :ref:`system_controller`


Perform Queries
-----------------

Displays the number of configuration entries in the LinOTP database.

.. code::

 https://<LINOTP>/monitoring/config?session=SESSIONCOOKIE

*Example:*

.. code::

 https://linotp.example.net/monitoring/config?session=45e939b02[...]

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "sqlresolver": 1,
         "total": 176,
         "realms": 4,
         "passwdresolver": 0,
         "sync": true,
         "synctime": "2016-07-15 12:53:15.421162",
         "policies": 13,
         "netto": 56,
         "ldapresolver": 1,
         "now": "2016-07-15 13:07:25.138295"
      }
   },
   "id": 1
 }

License
------------------

Displays support and subscription information and can be used to monitor
whether the number of active tokens surmount the license or how many tokens can
still be assigned within the limits of the license.

.. code::

 https://<LINOTP>/monitoring/license?session=SESSIONCOOKIE


*Example:*

In this example the license is issued for 1000 active tokens. 780 tokens are
active right now so 220 additional tokens can be used.

.. code::

 https://linotp.example.net/license/config?session=45e939b02[...]

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "token-num": 1000,
         "token-active": 780,
         "token-left": 220
      }
   },
   "id": 1
 }


Storage encryption
--------------------------

Checks whether local key or HSM is used to encrypt new entries written to the database.

.. code::

 https://<LINOTP>/monitoring/storageEncryption?session=SESSIONCOOKIE


*Example*

.. code::

 https://linotp.example.net/license/storageEnrcyption?session=45e939b02[...]


 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "cryptmodul_type": "DefaultSecurityModule",
         "cryptmodul_name": "Default",
         "encryption": true
      }
   },
   "id": 1
 }

Tokens
-------------

Shows tokens per realm. Filters can be applied regarding the status of the token or which realm is displayed.

Available filters:

``realms``
 show tokens from certain realms.

``active``
 show only active tokens.

``inactive``
 show only inactive tokens.

``assigned``
 show only tokens assigned to users.

``unassigned``
 show only tokens not assigned to any user.

The states can be combined like this:

.. code::

 ...status=assigned%26active

.. code::

 https://<LINOTP>/monitoring/tokens?session=SESSIONCOOKIE[&status=[assigned|unassigned][active|inactive][&realm=REALM1[,REALM2]]


*Example - display tokens of all realms*

Please mind, that the total numbers of tokens can
be smaller than the sum of the tokens per realm - one token can be assigned to
more than one realm. So if a token is in realm1 and realm2 and realm3 it is
only counted once in total.

.. code::

 https://linotp.example.net/monitoring/tokens?session=45e939b02[...]

 {
   "version": "LinOTP 2.9rc2",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "Realms": {
            "realm1": {
               "total": 380
            },
            "monitoring": {
               "total": 210
            },
            "realm3": {
               "total": 100
            },
            "realm2": {
               "total": 200
            }
         },
         "Summary": {
            "total": 840
         }
      }
   },
   "id": 1
 }

*Example - display tokens of realm1 and realm2*

.. code::

 https://linotp.example.net/monitoring/tokens?session=45e939b02[...]&realms=realm1,realm2

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "Realms": {
            "realm1": {
               "total": 380
            },
            "realm2": {
               "total": 200
            }
         },
         "Summary": {
            "total": 570
         }
      }
   },
   "id": 1
 }

*Example: display all unassigned tokens from realm2*

.. code::

 https://linotp.example.net/monitoring/tokens?session=45e939b02[..]&status=unassigned&realms=realms2

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "Realms": {
            "realm2": {
               "total": 200,
               "unassigned": 35
            }
         },
         "Summary": {
            "total": 200,
            "unassigned": 35
         }
      }
   },
   "id": 1
 }


*Example - display all active and assigned tokens from realm1*

.. code::

 https://linotp.example.net/monitoring/tokens?session=45e939b02[...]&status=active%26assigned&realms=realms1

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "Realms": {
            "realm1": {
               "total": 380,
               "active&assigned": 320
            }
         },
         "Summary": {
            "total": 380,
            "active&assigned": 320
         }
      }
   },
   "id": 1
 }

UserIdResolver
-----------------

Displays the UserIdResolver for each realm and the number of users found.

*Example - display UserIdResolver information for all realms*

.. code::

 https://linotp.example.net/monitoring/userinfo?session=45e939b02[...]

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "Realms": {
            "realm1": {
               "ad1": 400
            },
            "monitoring": {
               "local": 5
            },
            "realm3": {
               "ad1": 400,
               "ad2": 318
            },
            "realm2": {
               "ad1": 400,
               "ad2": 318,
               "sql1": 210
            }
         }
      }
   },
   "id": 1
 }

*Example - display UserIdResolver information for realm1 and realm2*

.. code::

 https://linotp.example.net/monitoring/userinfo?session=45e939b02[...]&realms=realm1,realm2

.. code::

 {
   "version": "LinOTP 2.9",
   "jsonrpc": "2.0802",
   "result": {
      "status": true,
      "value": {
         "Realms": {
            "realm1": {
               "ad1": 400
            },
            "realm2": {
               "ad1": 400,
               "ad2": 318,
               "sql1": 210
            }
         }
      }
   },
   "id": 1
 }